package cmpe273.proj1.dao;

import java.util.List;

import cmpe273.proj1.model.Course;
import cmpe273.proj1.model.Instructor;

/**
 * This interface represents a contract for a DAO for the {@link Instructor} model.
 *
 * @author BalusC
 * @link http://balusc.blogspot.com/2008/07/dao-tutorial-data-layer.html
 */
public interface InstructorDAO {

    // Actions ------------------------------------------------------------------------------------

	/**
     * Returni The Instructor from the database matching the given ID, otherwise null.
     * @param id The ID of the Instructor to be returned.
     * @return The Instructor from the database matching the given ID, otherwise null.
     *   Note: individual instructors will be returned with their courses (will JOIN)
     * @throws DAOException If something fails at database level.
     */
    public Instructor find(Long id) throws DAOException;
    
    /**
     * Returni The Instructor from the database matching the given SSN style ID, otherwise null.
     * @param id The SSN style ID of the Instructor to be returned.
     * @return The Instructor from the database matching the given ID, otherwise null.
     *   Note: individual instructors will be returned with their courses (will JOIN)
     * @throws DAOException If something fails at database level.
     */
    public Instructor find(String id) throws DAOException;

    /**
     * Returns a list of all Instructors from the database ordered by Instructor ID. The list is never null and
     * is empty when the database does not contain any Instructor.
     * @param count Fetch instructors in batches of count (max 100)
     * @param page Fetch instructors in batches of count, returning the "page" page (1-indexed)
     * @param Flag to get basic instructor information (name, address, etc.) vs. getting full instructors with 
     *   course information, which requires JOIN
     * @return A list of all Instructors from the database ordered by Instructor ID.
     * @throws DAOException If something fails at database level.
     */
    public List<Instructor> list(int count, int page, boolean getCourses) throws DAOException;
    
    /**
     * Returns a list of all Instructors from the database ordered by Instructor ID that match non-null parameters.
     * The list is never null and is empty when the database does not contain any Instructor.
     * @param searchParams A Instructor object where those parameters to search by are not-null.
     * Search for strings is "LIKE '%param%'" (i.e. contains), search for integers is exact
     * Note: does not search for instructors by course -- use searchInstructorsEnrolledIn method for this
     * @param Flag to get basic instructor information (name, address, etc.) vs. getting full instructors with 
     *   course information, which requires JOIN
     * @return A list of all Instructors from the database ordered by Instructor ID that match search parameters.
     * @throws DAOException If something fails at database level.
     */
    public List<Instructor> search(Instructor searchParams, boolean getCourses) throws DAOException;
    
    /**
     * Returns a list of all Instructors from the database ordered by Instructor ID that are part of the input course.
     * The list is never null and is empty when the database does not contain any Instructor.
     * @param course A Course object representing the course to look for
     * @return A list of all Instructors from the database ordered by Instructor ID that match search parameters.
     * @throws DAOException If something fails at database level.
     */
    public List<Instructor> searchInstructorsTeaching(Course course) throws DAOException;

    /**
     * Create the given Instructor in the database. The Instructor ID must be null, otherwise it will throw
     * IllegalArgumentException. After creating, the DAO will set the obtained ID in the given Instructor.
     * @param i The Instructor to be created in the database.
     * @throws IllegalArgumentException If the Instructor ID is not null.
     * @throws DAOException If something fails at database level.
     */
    public void create(Instructor i) throws IllegalArgumentException, DAOException;

    /**
     * Update the given Instructor in the database. The Instructor ID must not be null, otherwise it will throw
     * IllegalArgumentException.  The password will not be updated.
     * @param i The Instructor to be updated in the database.
     * @throws IllegalArgumentException If the Instructor ID is null.
     * @throws DAOException If something fails at database level.
     */
    public void update(Instructor i) throws IllegalArgumentException, DAOException;
    
    /**
     * Update the given Instructor in the database. The Instructor ID must not be null, otherwise it will throw
     * IllegalArgumentException.
     * @param i The Instructor to be updated in the database.
     * @param c The Course to list the instructor as teacher.
     * @throws IllegalArgumentException If the Instructor ID is null.
     * @throws DAOException If something fails at database level.
     */
    public void addCourse(Instructor i, Course c) throws IllegalArgumentException, DAOException;

    /**
     * Update the given Instructor's password only.
     * @param i The Instructor to be updated in the database.
     * @param c The Course to remove the instructor as teacher.
     * @throws IllegalArgumentException If the Instructor ID is null.
     * @throws DAOException If something fails at database level.
     */
    public void removeCourse(Instructor i, Course c) throws IllegalArgumentException, DAOException;
    
    /**
     * Delete the given Instructor from the database. After deleting, the DAO will set the ID of the given
     * Instructor to null.
     * @param c The Instructor to be deleted from the database.
     * @throws DAOException If something fails at database level.
     */
    public void delete(Instructor i) throws DAOException;
}